/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package javax.servlet.jsp.tagext;

import javax.servlet.jsp.JspContext;

/**
 * Interface for defining Simple Tag Handlers.
 * 
 * <p>
 * Simple Tag Handlers differ from Classic Tag Handlers in that instead of
 * supporting <code>doStartTag()</code> and <code>doEndTag()</code>, the
 * <code>SimpleTag</code> interface provides a simple <code>doTag()</code>
 * method, which is called once and only once for any given tag invocation. All
 * tag logic, iteration, body evaluations, etc. are to be performed in this
 * single method. Thus, simple tag handlers have the equivalent power of
 * <code>BodyTag</code>, but with a much simpler lifecycle and interface.
 * </p>
 * 
 * <p>
 * To support body content, the <code>setJspBody()</code> method is provided.
 * The container invokes the <code>setJspBody()</code> method with a
 * <code>JspFragment</code> object encapsulating the body of the tag. The tag
 * handler implementation can call <code>invoke()</code> on that fragment to
 * evaluate the body as many times as it needs.
 * </p>
 * 
 * <p>
 * A SimpleTag handler must have a public no-args constructor. Most SimpleTag
 * handlers should extend SimpleTagSupport.
 * </p>
 * 
 * <p>
 * <b>Lifecycle</b>
 * </p>
 * 
 * <p>
 * The following is a non-normative, brief overview of the SimpleTag lifecycle.
 * Refer to the JSP Specification for details.
 * </p>
 * 
 * <ol>
 * <li>A new tag handler instance is created each time by the container by
 * calling the provided zero-args constructor. Unlike classic tag handlers,
 * simple tag handlers are never cached and reused by the JSP container.</li>
 * <li>The <code>setJspContext()</code> and <code>setParent()</code>
 * methods are called by the container. The <code>setParent()</code> method is
 * only called if the element is nested within another tag invocation.</li>
 * <li>The setters for each attribute defined for this tag are called by the
 * container.</li>
 * <li>If a body exists, the <code>setJspBody()</code> method is called by
 * the container to set the body of this tag, as a <code>JspFragment</code>.
 * If the action element is empty in the page, this method is not called at all.</li>
 * <li>The <code>doTag()</code> method is called by the container. All tag
 * logic, iteration, body evaluations, etc. occur in this method.</li>
 * <li>The <code>doTag()</code> method returns and all variables are
 * synchronized.</li>
 * </ol>
 * 
 * @see SimpleTagSupport
 * @since 2.0
 */
public interface SimpleTag extends JspTag {

	/**
	 * Called by the container to invoke this tag. The implementation of this
	 * method is provided by the tag library developer, and handles all tag
	 * processing, body iteration, etc.
	 * 
	 * <p>
	 * The JSP container will resynchronize any AT_BEGIN and AT_END variables
	 * (defined by the associated tag file, TagExtraInfo, or TLD) after the
	 * invocation of doTag().
	 * 
	 * @throws javax.servlet.jsp.JspException
	 *             If an error occurred while processing this tag.
	 * @throws javax.servlet.jsp.SkipPageException
	 *             If the page that (either directly or indirectly) invoked this
	 *             tag is to cease evaluation. A Simple Tag Handler generated
	 *             from a tag file must throw this exception if an invoked
	 *             Classic Tag Handler returned SKIP_PAGE or if an invoked
	 *             Simple Tag Handler threw SkipPageException or if an invoked
	 *             Jsp Fragment threw a SkipPageException.
	 * @throws java.io.IOException
	 *             If there was an error writing to the output stream.
	 */
	public void doTag() throws javax.servlet.jsp.JspException,
			java.io.IOException;

	/**
	 * Sets the parent of this tag, for collaboration purposes.
	 * <p>
	 * The container invokes this method only if this tag invocation is nested
	 * within another tag invocation.
	 * 
	 * @param parent
	 *            the tag that encloses this tag
	 */
	public void setParent(JspTag parent);

	/**
	 * Returns the parent of this tag, for collaboration purposes.
	 * 
	 * @return the parent of this tag
	 */
	public JspTag getParent();

	/**
	 * Called by the container to provide this tag handler with the
	 * <code>JspContext</code> for this invocation. An implementation should
	 * save this value.
	 * 
	 * @param pc
	 *            the page context for this invocation
	 * @see Tag#setPageContext
	 */
	public void setJspContext(JspContext pc);

	/**
	 * Provides the body of this tag as a JspFragment object, able to be invoked
	 * zero or more times by the tag handler.
	 * <p>
	 * This method is invoked by the JSP page implementation object prior to
	 * <code>doTag()</code>. If the action element is empty in the page, this
	 * method is not called at all.
	 * 
	 * @param jspBody
	 *            The fragment encapsulating the body of this tag.
	 */
	public void setJspBody(JspFragment jspBody);

}
